The folders at this level contain the stages that currently exist for a
tutorial on using resources. The parts are numbered in order, but tend to
skip around a little (to better show the magnitude of changes from one part
to another). The source code does not necessarily follow all of the
conventions that the official DTS sample source code does. If you're
looking for a good programming style to follow, use their code. If you're
just trying to figure out what it all means, then this stage by stage
approach should be very useful.
This version was written using APW C and Rez. The APW C files can be
compiled without modifications using MPW IIGS C, but the Rez sources will
need one minor change in order to work with RezIIGS. You'll have to
change the "#include types.rez" to "#include TypesIIGS.r" (otherwise,
RezIIGS won't be able to find the standard resource types).
If there's an overwhelming demand for this approach in another language,
then perhaps I can be persuaded to change languages (or make clones of
this available in other languages). Send email requests to
"Bit.Bucket"... (the real info on where to send requests is at the end
of this file).
The tutorial is set up to make the change from one stage to the next as
small as possible (without being meaningless). The first part simply
shows how to startup and shutdown the tools using a tool startup list
kept in a resource. Once the tools are started up, the application calls
SysBeep three times (resulting in three beeps), shuts down the tools,
and quits.
Part 2 adds a menu bar full of menus after the tools are started and before
the triple beeps. The Apple menu (with desk accessories inserted), the
File menu, and the Edit menu are all installed. These menus closely follow
the Human Interface Guidelines with the exception that the items relating
to printing are NOT in the menus.
Part 2.5 is simply part 2 with an event loop instead of three beeps. This
allows you to explore a "minimum" application that uses resources. Desk
accessories are functional and can use the Edit menu.
Part 3 opens a window (using a template in a resource, naturally) that has
a couple of controls in it. The controls are kept in resources and are
active - the simple button can be clicked on and will highlight (notice
that there is NO source code driving this??? TaskMaster does the dirty
work for us). The text edit field works also - you can cut/copy/paste
to and from it, words will automatically wrap to stay within it, and the
scroll back becomes active if enough text is added to fill the visible
region. Again, notice that there is nothing in our application driving
this - TaskMaster is doing it for us. The window can be moved around the
desktop, but can't be closed.
The controls are added to the window AFTER it has been created using
NewControl2. This was done in accordance with IIGS Tech Note #82
(Controlling the Control Manager). Tech Note #82 warns us that NewWindow2
doesn't set the Graf Port correctly before automatically installing the
controls in the window. We work around this by not letting NewWindow2
automatically install our controls - we install them with a call to
NewControl2 _AFTER_ we set the current GrafPort to the newly created one
(created by NewWindow2). We stop the automatic installation by simply
putting a NULL in the second to last field of the rWindParam1 resource for
our window (see the rTutor.Rez source for details). If you're lost by all
of this, then get IIGS Tech Note #82 and read it.
Since several new routines had to be added to the source code to implement
the event loop and to implement the window, I split the changes into two
smaller parts. That's why there is a part 2.5 and a part 3. Part 2.5 is
half way (sort of) between part 2 and part 3. This should make it easier
to see what had to be added to the application, and to the resource fork,
to move from one part to the next.
Part 3.2 changes the About box from a simple beep (added in part 2.5) to
an Alert Window. The Alert Window is a custom size and shows how to imbed
formatting characters in the text. The Alert Window itself is a custom
size - this was done to further demonstrate the flexibility of the
AlertWindow tool call. I opted not to include an icon in the Alert Window
because that causes the text to be pushed off of true center. I could have
compensated for that by padding the text with trailing white space, but I
wanted to keep things simple for now. I'll leave the icon and re-centering
as an exercise for the reader... <grin>
Part 3.2's Rez source has been split into two files. The first file is
simply the stuff from Part 3 and the new file is the Alert Window's
definition. I split it into two parts to highlight Rez's ability to append
new resources onto an existing file and to show Rez's ability to include
already compiled resources. Both of these techniques SHOULD be part of
your development cycle. Why? Because there's no point in recompiling
resources that haven't changed! By splitting them into seperate files, you
can compile ONLY the parts that have changed (making your compile times
shorter). The ability to "include" pre-compiled resources provides you with
an easy way to implement standard resource "libraries" - i.e.: already
compiled resource forks with the resources you use in all applications.
Part 3.2 also comes with a second MAKE file. The second one assumes you've
already run the first one and won't work if you haven't. The point of the
second one is to further highlight the use of "include" and append (via
the "-a" flag on the command line). It also shows how to define, on the
command line, constants used within the Rez files themselves. Being able to
set constants on the command line allows you MUCH greater control over
conditional compiles. To see both versions of the second MAKE file, you
have to read the information it sends to the screen (or print it) and make
a couple of MINOR edits to the file (to comment out the first method and
uncomment the second one).
Part 3.3 shows how to use icons and cursors that are stored as resources. The current template in Types.Rez (and TypesIIGS.R) are awkward to work with and will change to match those found in the Tech Note on additional resource types. This awkwardness doesn't really interfere with this Part of the resource tutorial, it's just generally annoying.
The MAKE files used for this tutorial assume that you have either the
"Programming Tools & Interfaces for APW" package or the "APW Tools &
Interfaces" package. The "Programming Tools..." package is no longer
available (it was replaced by the newer "APW Tools..." package). If you
have the older package, then contact either APDA or Developer Tools
Express (1-800-282-2732) and order the update from the old package to the
new one (it's $25). The part number for the update package is A0241LL/A.
The new package ("APW Tools & Interfaces") is $50 and can also be ordered
from either APDA or Developer Tools Express (both places use the same phone
number: 1-800-282-2732). If you don't have either of these packages, then
call APDA (or Developer Tools Express) and order part # A0240LL/A to get
the full package. Both the update and the full package include new
interfaces for APW C and APW Assembly - these interfaces have been
extensively reviewed by DTS, engineering, etc to make them the best
interfaces in a long time.
The MAKE files require Rez, LinkIIGS, and Duplicate (all three of which are
in the packages I just mentioned). If you're building these examples with
ORCA/C, then you'll need to use the ORCA linker or run the CrunchIIGS script
before you call LinkIIGS. You'll also have to change the LinkIIGS command
line (since ORCA/C doesn't use Start.root). The ORCA/C MAKE file would be
